=head1 PURPOSE

This package should serve as a base for all database helpers. It provides a default set
of methods that allow the actual helper module to only provide the parts of the API it chooses.

Generally, these methods will be no-ops. They're mostly here as an implementation guide
for Helper authors, and so the main code doesn't need to worry about what methods are
available for each database. 

=cut

package dbPicasso::Database::Helper::db;

use base qw(DBI::db);

=head1 splitQueryBatch

Allow for batch separations in a single 'execute' action. This will
split the query text on line separations (like Sybase/SQL Server's 'go')
and pass back a listref of individual queries. 

We don't necessarily want to split apart every statement. Multiple statement batches 
are perfectly legal in most databases. 

A simple example using the 'go' keyword:

select 1
go
select 2

This would execute the two select statements in two seperate calls to the database,
instead of sending them as a single batch.

You may want to overload this, but it'll probably be ok for most drivers.

=cut

sub splitQueryBatch
{
	my $self = shift;
	my $sql = shift;

	my @batches = split /^go[\s]*$/mi, $sql;

	return \@batches;
	
}

sub connected
{
	my $db = shift;
	my ($dsn, $user, $pass, $attrs) = @_;
	
	return 1; # doesn't really mean anything.
}

sub disconnect
{
	my $self = shift;

	print "Disconnecting database handle.\n";
	eval { $self->SUPER::disconnect };

	return 1;
}

sub execQuery
{
	my $self = shift;
	my $query = shift; # string containing individual query

	print "--- " . scalar (localtime(time)) .  " Executing SQL: ---\n\n$query\n---\n\n";

	my $sth = $self->prepare($query) or return undef;
	$sth->execute or return undef;

	return $sth;
}
# stubs

sub init { 1; }
sub generate_DSN { undef; }
sub get_object_DDL { undef; }
sub set_error_handler { undef; }
sub _post_connect { 1; }




package dbPicasso::Database::Helper::st;

use base qw(DBI::st);

=header more_results

Calls $class->more_results_func and expects a string back indicating which 
DBD function to call to determine whether there are more resultsets pending 
download. The string varies per driver (usually "driver_more_results"), but the 
logic is always the same. If multiple result sets are not supported, the helper 

Returns true if more resultsets are pending, false otherwise.

=cut

sub more_results
{
	my $sth = shift;

	# Helpers return 'undef' if multiple result sets are not supported. 
	my $func = $sth->more_results_func or return undef;

	return $sth	? $sth->{$func} 
				: undef;
}


# Default is that multiple result sets are not supported.
sub more_results_func { return undef; }

1;
